PsL Monthly 1993 December

home *** CD-ROM | disk | FTP | other *** search

/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / pascal / tpref.exe / TPR8.TXT < prev next >

Wrap

Text File | 1992-10-19 | 70.3 KB | 1,854 lines

Chapter 8 of the Turbo Pascal Reference The Turbo Vision Reference (continued) This chapter is part of the Turbo Pascal Reference electronic freeware book (C) Copyright 1992 by Ed Mitchell. This freeware book contains supplementary material to Borland Pascal Developer's Guide, published by Que Corporation, 1992. However, Que Corporation has no affiliation with nor responsibility for the content of this free book. Please see Chapter 1 of the Turbo Pascal Reference for important information about your right to distribute and use this material freely. If you find this material of use, I would appreciate your purchase of one my books, such as the Borland Pascal Developer's Guide or Secrets of the Borland C++ Masters, Sams Books, 1992. Thank you. For additional information on using Turbo Vision, including a detailed tutorial, please see Chapters 11 through 16 of the Borland Pascal Developer's Guide. RepeatDelay variable ------------------------------------------------------------ Declaration: RepeatDelay: Word = 8; Unit: Drivers Purpose: Determines the number of clock ticks that must occur before generating an evMouseAuto event. evMouseAuto events are automatically generated while the mouse button is held down. A clock tick is 1/18.2 seconds, so the default value of 8/18.2 is set at approximately 1/2 second. See: evXXXX constants, DoubleDelay SaveCtrlBreak variable ------------------------------------------------------------ Declaration: SaveCtrlBreak: Boolean = False; Unit: Drivers Purpose: This internal variable is set to the state of the DOS Ctrl-break checking at program initialization; at program termination, DOS's Ctrl-break trapping is restored to the value saved in SaveCtrlBreak. See: InitSysError, DoneSysError sbXXXX constants ------------------------------------------------------------ Scrollbar constants Constant Value Usage sbLeftArrow 0 The horizontal scroll bar's left arrow. sbRightArrow 1 Horizontal scroll bar's right arrow. sbPageLeft 2 The page area to the left of the position indicator. sbPageRight 3 The page indicator to the right of the indicator. sbUpArrow 4 Vertical scroll bar's up arrow. sbDownArrow 5 Vertical scroll bar's down arrow. sbPageUp 6 Paging area above the position indicator. sbPageDown 7 Paging area below the position indicator. sbIndicator 8 Position indicator on the scroll bar. sbHorizontal $0000 The scroll bar is horizontal. sbVertical $0001 The scroll bar is vertical. sbHandleKeyboard $0002 Scroll bar accepts keyboard commands. Use one of the first 9 sbXXXX constants as a parameter to TScrollBar.ScrollStep. The last 3 sbXXXX constants, sbHorizontal, sbVertical, sbHandleKeyboard are used to specify a horizontal, vertical, or keyboard accessable scrollbar when a scroll bar is created using the TWindow.StandardScrollBar function. See: TScrollBar.ScrollStep, TScrollBar, TWindow.StandardScrollBar ScreenBuffer variable ------------------------------------------------------------ Declaration: ScreenBuffer: Pointer; Unit: Drivers Purpose: This internal pointer is initialized by InitVideo and keeps track of the location of the video screen buffer. ScreenHeight variable ------------------------------------------------------------ Declaration: ScreenHeight : Byte; Unit: Drivers Purpose: Holds the current height of the screen, in lines. For example, 25, 43 or 50 would be typical values. See: SetVideoMode ScreenMode variable ------------------------------------------------------------ Declaration: ScreenMode : Word; Unit: Drivers Purpose: Contains the current video mode as determined by the smXXXX constants passed to the SetVideoMode procedure. See: SetVideoMode, smXXXX constants ScreenWidth variable ------------------------------------------------------------ Declaration: ScreenWidth : Byte; Unit: Drivers Holds the current width of the screen in number of characters per line (for example, 80). SetMemTop procedure ------------------------------------------------------------ Declaration: procedure SetMemTop(MemTop : Pointer); Unit: Memory Purpose: SetMemTop sets the top of the memory block allocated to an application. Initially, MemTop is set to the top of the heap, stored in HeapEnd. By resetting the top of memory to the HeapPtr, all the remaining free memory is available for other uses. This is especially useful when shelling out to another application, as shown in this example code from TVSHELL8.PAS (see Chapters 11-12 in Borland Pascal Developer's Guide): procedure TShell.RunProgram ( ProgName, ParamStr : String ); { Launches the program in 'ProgName' with the command line parameters in 'ParamStr' } begin ClrScr; DoneSysError; DoneEvents; DoneVideo; DoneMemory; SetMemTop(HeapPtr); SwapVectors; Exec( ProgName, ParamStr ); SwapVectors; SetMemTop(HeapEnd); InitMemory; InitVideo; InitEvents; InitSysError; Shell.ReDraw; end; { RunProgram } SelectMode type ------------------------------------------------------------ Declaration: SelectMode = (NormalSelect, EnterSelect, LeaveSelect); Unit: Views Purpose: An internal value used by Turbo Vision. SetVideoMode procedure ------------------------------------------------------------ Declaration: procedure SetVideoMode( Mode: Word ); Unit: Drivers Purpose: Use this (or more commonly TProgram.SetScreenMode) to select 25 or 43/50 line screen height, in conjunction with selecting the color, black & white or monochrome palettes. To change to the color palette, write, SetVideoMode( smCO80 ); where smCO80 is one of the smXXXX screen mode constants. Optionally, to select 43/50 line mode, add the smFont8x8 constant to the color selection constant. For example, SetVideoMode( smMono + smFont8x8 ); Normally, you should use TProgram.SetScreenMode, which has the same parameter value, to change the screen color or screen size. SetScreenMode properly handles resetting of the application palettes, repositioning the mouse pointer and so on. See: TProgram.SetScreenMode, smXXXX constants sfXXXX constants ------------------------------------------------------------ State Flag constants Use TView.SetState to set the state bits, from the table below, into a TView's State field. Example usage: SetState( sfCursorIns, True ); where the first parameter is the state value to change, and the second parameter is True to enable the selected condition, or False to disable the selected condition. Some of the bits are not normally set by the programmer but rather by methods in Turbo Vision. You can, however, read and test the values in TView.State directly. Constant Value Usage sfVisible $0001 Set when the view is visible in front of its owner (for example, a button on a dialog) but note that a visible view's owner may itself be hidden from view. Call TView.Exposed to determine if a view is actually visible on the screen, and use TView.Hide to clear this bit and hide the view, and TView.Show to set this bit and make the view visible. sfCursorVis $0002 Set when the view's cursor is visible. Use TView.ShowCursor to make the cursor visible and set this bit, or TView.HideCursor to hide the cursor and clear this bit. sfCursorIns $0004 Set when the cursor is a solid block (the "insert" cursor), clear when the cursor is an underscore (the "overstrike" cursor). Call TView.BlockCursor to set this bit, and TView.NormalCursor to clear the bit. sfShadow $0008 Set when the view has a shadow. sfActive $0010 Set whenever the view is an active window or a subview within an active window. For example, when using the IDE to edit multiple files, only the editor that you are currently using is the active window. sfSelected $0020 Set when this view is selected. (See TView.Selected). sfFocused $0040 If the view is part of the focus chain (see Chapter 13, "More Turbo Vision Features" in the Borland Pascal Developer's Guide), then this bit is set. sfDragging $0080 Set whenever the view is being dragged. sfDisabled $0100 Set if the view has been disabled and is no longer processing events. sfModal $0200 Whenever a view is displayed using the ExecView call, that view becomes a modal view (as compared to a view that has been inserted into the desktop). This bit is set when the view is the modal view and controls how events are sent through the view hierarchy. sfExposed $0800 Set when a view is possibly visible on the screen. Don't check this flag directly because a visible view can still be hidden due to clipping. Instead, call TView.Exposed to determine if the view is actually visible. See: TView.BlockCursor, TView.Exposed, TView.Hide, TView.HideCursor, TView.NormalCursor, TView.SetState, TView.Show, TView.ShowCursor, ShadowAttr variable ------------------------------------------------------------ Declaration: ShadowAttr: Byte = $08; Unit: Views Purpose: The ShadowAttr byte contains the video attribute for the color of the shadow display on some views and windows. See Chapter 13, "More Turbo Vision Features" in the Borland Pascal Developer's Guide for details on selecting different colors for video attribute bytes See: ShadowSize ShadowSize variable ------------------------------------------------------------ Declaration: ShadowSize: TPoint = (X: 2; Y: 1); Unit: Views Purpose: ShadowSize determines the size of the shadow area on those views that contain a shadow. The default value is 2 characters wide and 1 character high. See: ShadowAttr ShowMarkers variable ------------------------------------------------------------ Declaration: ShowMarkers: Boolean; Unit: Drivers Purpose: When using color displays, Turbo Vision uses different colors to highlight the default button selections, the location of the list box cursor and so on. When using the monochrome color palette, Turbo Vision adds small marker characters to various controls to make them easier to identify and when necessary to highlight a default selection. For example, default buttons have small right and left arrows to highlight the default button: -> [ Okay ] <- [Cancel] When the monochrome color palette is selected, ShowMarkers is set to True and is normally set False for the other color palettes. If you wish, you can set ShowMarkers True for both CColor and CBlackWhite palettes. ShowMouse procedure ------------------------------------------------------------ Declaration: procedure ShowMouse Unit: Drivers Purpose: ShowMouse is the opposite of the HideMouse. Call HideMouse to hide the mouse cursor and simultaneously increment a "mouse hidden counter". ShowMouse decrements the counter, and when it reaches zero, makes the mouse cursor visible again on the screen. See: HideMouse smXXXX constants ------------------------------------------------------------ Screen Mode Constants Use the constants from the table below when selecting Black & White, Color or Monochrome color palettes, or switching between 25 and 43- or 50 line display modes. Use of these constants is described in "The Set Up Program Dialog" in Chapter 12, and also in Chapter 13 of the Borland Pascal Developer's Guide. Constant Value Usage smBW80 $0002 Black and white/gray scale smCO80 $0003 Color mode smMono $0004 Monochrome mode smFont8x8 $0100 43 or 50 line modes See: SetVideoMode, ScreenMode, TProgram.SetScreenMode SpecialChars variable ------------------------------------------------------------ Declaration: SpecialChars: array [0..5] of Char = (#175, #174, #26, #27, ' ', ' ') Unit: Views Purpose: These constants define the special marker characters used when the ShowMarkers variable is set to True. See: ShowMarkers stXXXX constants ------------------------------------------------------------ Stream constants These constants are used when opening a stream file, to specify the access mode, and by the streams system to return error condition codes. For additional information, see Chapter 21, Streams. Stream access modes passed to the TStream.Init constructor Constant Value Usage stCreate $3C00 Create and open the file stOpenRead $3D00 Open an existing file as a read-only file stOpenWrite $3D01 Open an existing file as write-only. stOpen $3D02 Open an existing file with read/write access Stream error codes set in TStream.Status Constant Value Usage stOk 0 No error stError -1 Access error occurred stInitError -2 Unable to initialize the stream stReadError -3 An attempt was made to read past the end of the file stWriteError -4 For some reason (perhaps out of disk space) the stream could not be expanded. stGetError -5 An unregistered object type was found in the file by the Get method. stPutError -6 Put tried to write an unregistered object type to the stream StartupMode variable ------------------------------------------------------------ Declaration: StartupMode : Word; Unit: Drivers Purpose: This internal variable stores the existing screen mode before Turbo Vision switches to a new screen mode. See: DoneVideo, ScreenMode StatusLine variable ------------------------------------------------------------ Declaration: StatusLine: PStatusLine = nil; Unit: App Purpose: StatusLine is initialized by the call to TProgram.InitStatusLine. See Chapter 14, Turbo Vision Tutorial for a detailed description of initialization a program's status line. StreamError variable ------------------------------------------------------------ Declaration: StreamError: Pointer = nil; Unit: Objects Purpose: To override all stream error handling, set StreamError to point to a far procedure that you have defined. Thereafter, whenever any error occurs, on any stream that is in use, your procedure will receive control. This enables you to write a single procedure to intercept and process all stream error conditions. Alternately, you can override TStream.Error to intercept error conditions for individual streams. Example usage: procedure HandleStreamErr( var S : TStream); far; ... StreamError := @HandleStreamErr; SysColorAttr variable ------------------------------------------------------------ Declaration: SysColorAttr: Word = $4E4F; Unit: Drivers Purpose: On color displays, SysColorAttr specifies the attribute bytes for system error messages. (SysMonoAttr specifies the attribute bytes for monochrome ). System error messages are DOS crtical errors (such as floppy disk drive not accessible) and other device type errors. System errors are displayed on the status line in the color specified by the second part of SysColorAttr, $4F, white on red text. The first part, $4E, is used for highlighting command keys, such as Enter or Esc. See: SystemError, SysMonoAttr, Chapter 13, "More Turbo Vision Features". SysErrActive variable ------------------------------------------------------------ Declaration: SysErrActive : Boolean = False; Unit: Drivers Purpose: If True, then the system error handler is available for use. SysErrorFunc variable ------------------------------------------------------------ Declaration: SysErrorFunc : TSysErrorFunc = SystemError; Unit: Drivers Purpose: SysErrorFunc points to the system error handling procedure. You can override system error handling by writing your own procedure and assigning it to the SysErrorFunc variable. The default system error handler is defined as, function SystemError (ErrorCode: Integer; Drive: Byte): Integer; where ErrorCode is a value from the table below, and Drive is the drive number (A=1, B=1, C=3, and so on). SystemError should return 0 if the user requests to retry the operation or 1 if the user elected to abort the function. Table of System Error Codes Error code Usage 0 Disk is write protected 1 Critical disk error 2 Disk is not ready 3 Critical disk error 4 Data integrity error 5 Critical disk error 6 Seek error 7 Unknown media type 8 Sector not found 9 Printer out of paper 10 Write fault 11 Read fault 12 Hardware failure 13 Bad memory image of file allocation table 14 Device access error 15 Drive swap notification (floppy disks have changed) See: SysColorAttr, SysErrActive, SysErrorFunc, SysMonoAttr, SystemError, TSysErrorFunc, InitSysError SysMonoAttr variable ------------------------------------------------------------ Declaration: SysMonoAttr: Word = $7070; Unit: Drivers Purpose: On monochrome displays, SysMonoAttr specifies the attribute bytes for system error messages. (SysColorAttr specifies the attribute bytes for color). System error messages are DOS crtical errors (such as floppy disk drive not accessible) and other device type errors. See SysColorAttr for more information about the attribute values. See: SystemError, SysColorAttr, Chapter 13, "More Turbo Vision Features" in Borland Pascal Developer's Guide. SystemError function ------------------------------------------------------------ Declaration: function SystemError( ErrorCode: Integer; Drive:Byte): Integer; Unit: Drivers Purpose: This function handles system errors (such as DOS critical errors). See SysErrorFunc for details on the parameters and their values. SystemError returns 0 if the user requests that the operation be retried, and 1 if the user elects to cancel the operation. See: SysErrorFunc TApplication object ------------------------------------------------------------ Turbo Vision Hierarchy TObject TView TGroup TProgram TApplication Discussion The TApplication object is the generic application from which most of the Turbo Vision programs you write will be derived. For examples, see the TVSHELL sample programs of Chapters 11-12 in the Borland Pascal Developer's Guide. As shown in Listing 11.1 (of the Developer's Guide), TShell is defined as an instance of TApplicatio. TApplication is nearly identical to TProgram; the only difference is in the Init and Done destructors. Commonly Used Features Generally, the only methods used are TApplication.Init, TApplication.Done, and TApplication.Run, which is inherited from TProgram.Run. See also TProgram for other methods that are available to TApplication objects. Example type TShell = object(TApplication) DirWindow : PDirectoryWindow; procedure InitMenuBar; virtual; procedure InitStatusLine; virtual; constructor Init; end; { TShell } var Shell : TShell; { Create an instance of the TShell object } procedure TShell.InitMenuBar; { Purpose: Defines the pulldown menus used in Shell } var Bounds: TRect; begin TShell.GetExtent(Bounds); Bounds.B.Y := Bounds.A.Y + 1; MenuBar := New(PMenuBar, Init(Bounds, NewMenu( NewSubMenu('~R~un', hcNoContext, NewMenu( NewItem('~R~un', '', 0, cmRunProgram, hcNoContext, ... end; procedure TShell.InitStatusLine; { Purpose: Defines the Status Line shown on the bottom line of the screen within TShell } var Bounds: TRect; begin GetExtent(Bounds); Bounds.A.Y := Bounds.B.Y - 1; StatusLine := New(PStatusLine, Init(Bounds, NewStatusDef(0, $FFFF, NewStatusKey('', kbF10, cmMenu, NewStatusKey('~Alt-X~ Exit', kbAltX, cmQuit, NewStatusKey('~F2~ Copy', kbF2, cmCopy, NewStatusKey('~F3~ Close', kbF3, cmClose, nil)))), nil) )); end; { TShell.InitStatusLine } constructor TShell.Init; var Bounds : TRect; begin TApplication.Init; end; { TShell.Init } begin Shell.Init; Shell.Run; Shell.Done; end. Fields none Methods destructor Done; virtual; Calls TProgram.Done, DoneHistory, DoneSysError, DoneEvents, DoneVideo, and DoneMemory. constructor Init; Calls InitMemory, InitVideo, InitEvents, InitSysError, InitHistory and TProgram.Init. TBackground object ------------------------------------------------------------ Turbo Vision Hierarchy TObject TView TBackground Discussion TBackground contains the background pattern that forms the backdrop of most Turbo Vision applications. TBackground is automatically initialized by the TDeskTop object that owns all of the application views. Commonly Used Features Normally, you will have no need to directly use the TBackground object. However, if you wish to create a different background object, you will need to override TProgram.InitDeskTop, to instantiate a new TDeskTop with an overridden TDeskTop.NewBackground function. NewBackground, in turn, creates the new TBackground object by calling TBackground.Init to specify a new background pattern. Example: 1 { DEMOTBAC.PAS } 2 program DemoTBackground; 3 4 uses 5 Objects, App, Views; 6 7 type 8 TSampleProgram = object(TApplication) 9 procedure InitDeskTop; virtual; 10 end; 11 12 PNewDeskTop = ^TNewDeskTop; 13 TNewDeskTop = object(TDeskTop) 14 procedure InitBackground; virtual; 15 end; 16 17 var 18 SampleProgram : TSampleProgram; 19 20 21 procedure TNewDeskTop.InitBackground; 22 Var 23 Bounds: TRect; 24 Temp : PBackground; 25 begin 26 { Program never gets here ???? } 27 Bounds.Assign( 0, 1, 80, 24 ); 28 Temp := New( PBackground, Init( Bounds, Char($FF) ) ); 29 Insert(Temp); 30 Background := Temp; 31 end; 32 33 34 procedure TSampleProgram.InitDeskTop; 35 Var 36 Bounds: TRect; 37 begin 38 Bounds.Assign( 1, 0, 80, 24 ); 39 DeskTop := New( PNewDeskTop, Init( Bounds ) ); 40 end; 41 42 43 begin 44 with SampleProgram do 45 begin 46 Init; 47 Run; 48 Done; 49 end; 50 end. 51 Fields Pattern: Char; Contains the bit pattern describing the background's appearance. This value is initialized by TDeskTop.InitBackground calling TBackground.Init. Methods procedure Draw; virtual; Using the palette returned by GetPalette, draws the background using the specified Pattern. You can override this method to create a new type of background, say perhaps one containing text or boxes or what ever you desire. To do that, derive a new TDeskTop object and a new TBackground object, using the method outline in the sample Listing above, and override TBackground.Draw to display the background in the format that your require. function GetPalette: PPalette; virtual; Returns a pointer to the CBackground color palette. To change the color scheme, you need to override this method (see TBackground.Draw, above). constructor Init(var Bounds: TRect; APattern: Char); Call TBackground.Init via TDeskTop.InitBackground, to create a new background object of the size specified by Bounds, and having the replicated bit pattern indicated by APattern. See: TDeskTop.InitBackground constructor Load(var S: TStream); Creates a new TBackground object and reads its attributes from stream S by calling TView.Load, and then S.Read(Pattern). procedure Store(var S :TStream); Writes the TBackground object to stream S, by calling TView.Store, and then S.Write(Pattern). TBufStream object ------------------------------------------------------------ Turbo Vision Hierarchy TObject TStream TDosStream TBufStream Discussion The TBufStream object type is a derivative of TStream and TDosStream and is probably the type you will most often use for writing and reading streams to and from disk files. TBufStream implements a buffered version of TDosStream, which greatly improves the speed and efficiency of stream I/O, particularly when writing or reading a lot of small objects. See Chapter 15, "Streams" in the Borland Pascal Developer's Guide for a tutorial on the use of stream I/O. See: TDosStream, TStream, stXXXX constants Commonly Used Features Generally, you will use the TBufStream.Init method to open a stream file for access, the TBufStream.Read and TBufStream.Write methods for performing input and output, and TBufStream.Done to close and dispose of the object. For random access streams, you will use TBufStream.Seek to position the file pointer to the proper object reocrd. You may also wish to use TBufStream.Flush or TBufStream.Truncate, as appropriate. Example 1 { DEMOTBUF.PAS } 2 var 3 PhoneBook : PCollection; 4 PhoneBookFile : TBufStream; 5 6 ... 7 8 9 { TPersonInfo is a collection object holding name and address information } 10 procedure TPersonInfo.Store ( var S : TStream ); 11 begin 12 13 S.Write( Name, SizeOf( Name )); 14 S.Write( Address, SizeOf( Address )); 15 S.Write( City, SizeOf( City )); 16 S.Write( State, SizeOf( State )); 17 S.Write( Zip, SizeOf( Zip )); 18 S.Write( Age, SizeOf( Age )); 19 20 end; 21 22 23 constructor TPersonInfo.Load ( var S : TStream ); 24 begin 25 26 S.Read( Name, SizeOf( Name )); 27 S.Read( Address, SizeOf( Address )); 28 S.Read( City, SizeOf( City )); 29 S.Read( State, SizeOf( State )); 30 S.Read( Zip, SizeOf( Zip )); 31 S.Read( Age, SizeOf( Age )); 32 33 end; 34 35 ... 36 37 { Register the PersonInfo object type } 38 RegisterType( RPersonInfo ); 39 40 { Open the stream file } 41 PhoneBookFile.Init('FONEBOOK.DAT', stCreate, 1024 ); 42 43 { Tell the PhoneBook collection to put itself to the stream } 44 PhoneBookFile.Put( PhoneBook ); 45 46 { Close the file } 47 PhoneBookFile.Done; Fields BufEnd: Word; { Read only } BufEnd is an index to the last used byte in Buffer. Buffer: Pointer; { Read only } Points to the beginning of the stream's buffer. BufPtr: Word; { Read only } Points to the current location in Buffer. BufSize: Word; { Read only } Contains the size of the buffer, in bytes. Methods destructor Done; virtual; Flushes the buffer to disk, closes the file and disposes of the stream object. procedure Flush; virtual; Override: Never Forces the buffer contents to be written out to disk. function GetPos: Longnt; virtual; Override: Never Gives the stream's current position relative to the start of the sream. Important: This is not the same as BufPtr which is the current position relative to the start of the current buffer only. GetPos corresponds to the action of Seek, below, which positions the stream's current location to a byte location in the stream file. function GetSize: Longint; virtual; Override: Never Writes the contents of the buffer out to disk (via Flush) and returns the total number of bytes in the stream. constructor Init( Filename: FNameStr; Mode, Size : Word); Use Init to create and initialize a stream, using the parameters Filename to contain the name of the file open, setting the Mode parameter to stCreate, stOpenRead, stOpenWrite or stOpen, and Size to the number of bytes to allocate for a buffer area. procedure Read( var Buf; Count: Word); virtual; Override: Never Use Read to read Count bytes from the stream and into the Buf parameter. Read begins at the stream's current position (as determined by Seek or beginning at the end of the previous Read operation). See: Chapter 15, "Streams" in the Borland Pascal Developer's Guide, Seek, Write procedure Seek(Pos : Longint); virtual; Override: Never Empties the contents of the Buffer to disk and then positions the current stream position to Pos. You can use Seek to implement random access to stream files (see Chapter 15, "Streams"). Be certain that if you are adding or multiplying values to compute the Pos parameter (for example, SizeOf(SomeObject) * Index), that you convert the parameters to Longint to avoid integer overflow errors. See: Chapter 15, "Streams" in the Borland Pascal Developer's Guide, GetPos, Read, Write procedure Truncate; virtual; Use Truncate to flush out the Buffer, and delete all data following the current position in the stream. procedure Write( var Buf; Count: Word); virtual; Use Write to copy Count bytes from the Buf parameter to the stream. See: Chapter 15, "Streams" in the Borland Pascal Developer's Guide, Read TButton object ------------------------------------------------------------ Turbo Vision Hierarchy TObject TView TButton Discussion Use the TButton object to place button controls into dialog boxes. Each time that a button is "pressed" by clicking on it with the mouse, or using a keyboard shortcut key or tabbing to the button and pressing SpaceBar or Enter, the button generates a cmXXXX command. Commonly Used Features Generally, you need only Init a TButton object and insert it in to the owning TGroup, which is typically a TDialog. You rarely need to override any of its methods or reference its fields. Example with Dialog^ do begin { Create the Okay and Cancel buttons } Bounds.Assign (7, 10, 16, 12 ); Insert( New( PButton, Init( Bounds, '~O~kay', cmOk, bfDefault ))); Bounds.Assign ( 24, 10, 33, 12 ); Insert( New( PButton, Init( Bounds, '~C~ancel', cmCancel, bfNormal ))); ... end; { with Dialog } Control := DeskTop^.ExecView( Dialog ); Fields AmDefault: Boolean; { Read only } When True, this button is the default button, and when False, this is a normal button. Command : Word; { Read only } Holds the command code value that is generated when the button is pressed. Flags : Byte; { Read only } The flags byte is a bit mapped field indicating if the label text is left justified or center, and if the button is the default button in the group, or is a normal, non-default button. See: bfXXXX constants Title : PString; { Read only } Points the string containing the button's label text. Methods destructor Done; virtual; Disposes the memory allocated to Title and calls TView.Done. procedure Draw; virtual; Override: If needed. Draws the button using the palette returned by GetPalette, and by referencing the Flags, AmDefault and TView.State fields to display the button as a normal button, default button or disabled button, with left justified or centered title. function GetPalette: PPalette; virtual; Override: If needed. Returns a pointer to the CButton color palette, but can be overridden to provide other color choices. CButton entries are intended to map into the CDialog palette. If, for some reason the TButton is not inserted into a TDialog group, you will almost certainly have to override this function. procedure HandleEvent(var Event: TEvent); virtual; Override: If needed. Processes events received by the button. These include mouse clicks, keyboard short cut keys, Enter, SpaceBar, and several internal commands used to process evBroadcast messages notifying buttons when the default button changes. constructor Init(var Bounds: TRect; ATitle: TTitleStr; ACommand: Word; AFlags: Byte); Init is the only method that you are likely to use for the TButton object. Use Init to create a button with a size and location specified in Bounds, and a button label specified by ATtitle. Pass the cmXXXX command constant to ACommand, to be returned if the button is pressed. For the AFlags parameter, you can pass one of the bfXXXX constants to initialize this button as the bfDefault or bfNormal button, and can optionally or one of the contstants with bfLeftJustify left justify the button label instead of using the centering default. constructor Load(var S: TStream); Creates a new instance of a TButton object and reads its definition from stream S. Use the TButton.Load method, in conjunction with Store, for reading dialog boxes directly from resource files. This topic is covered in detail in chapter 16, "Resources" in the Borland Pascal Developer's Guide. See: TButton.Store procedure MakeDefault(Enable : Boolean); Call a button's MakeDefault method to force the button to become the default button, by setting Enable to True. If Enable is False, the default status of this button is removed. Normally, this is handled internally to the TDialog object that owns the button. procedure SetState( AState: Word; Enable: Boolean); virtual; If needed, call this method to change the TView.State field inherited from TView. If the button becomes sfSelected or sfActive, SetState automatically handles making the button the default or non-default, as needed. procedure Store( var S : TStream); Writes this button object out to stream S. Use in conjunction with Load for the creation and reading of resource files. See: TButton.Load TByteArray type ------------------------------------------------------------ Declaration: TByteArray = array[0..32767] of Byte; Unit: Objects Purpose: TByteArray is generic array of bytes useful for typecasting. TCheckBoxes object ------------------------------------------------------------ Turbo Vision Hierarchy TObject TView TCluster TRadioButtons TCheckBoxes Discussion Use TCheckBoxes to implement groups of check box controls in dialogs. Eachgroup can have up to 16 check boxes, any number of which may be "checked" at the same time. See Chapter 11, "Turbo Vision Tutorial" in the Borland Pascal Developer's Guide contains a tutorial on the creation and use of the TCheckBoxes object. Commonly Used Features Normally, you create groups of checkboxes using the inherited Init method. Rarely will you have a need to use or override the other methods. See: TCluster, TRadioButtons Fields None Methods procedure Draw; virtual; Draws the checkboxes by calling TCluster.DrawBox and sets each checkbox indicator to "[ ]" if the item is not checked, and to "[ X ]" if the item is checked. See TCluster.DrawBox for instructions on using that method to draw the indicators. You only need to override this method if you plan to use a different type of indicator for checkboxes. function Mark( Item: Integer ) : Boolean; virtual; The items in the check box cluster are numbered from 0 up to a maximum of 15 items. By passing the item number corresponding to a specific check box, you can test to see if the Item'th check box has been set to "[ X ]". See: TCheckBox.Press procedure Press( Item : Integer ); virtual; Press sets or clears a check box item. Like Mark, the parameter Item specifies which of the check boxes, from 0 up to a maximum of 15 to set or clear. Press toggles the check box: if the checked box is already checked, then Press clears it and vice versa. See: TCheckBox.Mark TCluster object ------------------------------------------------------------ Turbo Vision Hierarchy TObject TView TCluster TRadioButtons TCheckBoxes Discussion The TCluster objects are used to creat groups of dialog box controls. Both TRadioButtons and TCheckBoxes inherit almost all of their functionality from TCluster due to their strong similarities. Commonly Used Features Generally, you will use either TRadioButtons or TCheckBoxes and directly insert those controls into dialogs. While TCluster provides several fields and methods, these are primarily of interest if you are building a new cluster-type control. Fields Sel: Integer; { Read only } Sel indicates which of the buttons or check boxes is currently the active one. Strings : TStringCollection; { Read only } Strings is a collection containing the text of all the items in the control group. Value: Word; { Read only } Value holds the current setting of the control. For TCheckBoxes, Value is a bit pattern where each bit indicates the state of a checked box, and for TRadioButtons, Value is the item number of the button that is pressed. Methods destructor Done; virtual; Disposes of the Strings collection and calls TView.Done. function DataSize: Word; virtual; This function is used in conjunction with GetData and SetData, to obtain the SizeOf(Value). procedure DrawBox(Icon: String; Marker: Char); DrawBox draws the status indicator for each check box or icon and is called by TCheckBoxes.Draw or TRadioButtons.Draw. The Icon parameter holds '[ ]' for check boxes, or '( )' for radiobuttons. Marker contains the character to indicate the item is selected (for example, 'x' for checkboxes). procedure GetData(var Rec); virtual; Used to copy the Value field to Rec when retrieving dialog data. function GetHelpCtx: Word; virtual; Returns HelpCtx + Sel, where Sel is the current active item in the cluster. Using this method you can produce context sensitive help for individual items in each cluster. function GetPalette: PPalette; virtual; Returns a pointer to CCluster color palette. Override this method to implement a different color sheme for cluster items. procedure HandleEvent(var Event: TEvent); virtual; Handles selection of cluster items through the keyboard movement keys and SpaceBar (to toggle a selection). Other events are passed through to TView.HandleEvent. constructor Init( var Bounds: TRect; AStrings: PSItem); Use Init and nested calls to NewSItem to create an entire list of cluster items within the area described by Bounds. Normally, TCluster.Init is called via the derived objects TRadioButtons.Init or TCheckBoxes.Init, as shown in this example: Bounds.Assign( 24, 2, 40, 5); ColorOptions := New( PRadioButtons, Init( Bounds, NewSItem('~C~olor', NewSItem('~M~onochrome', NewSItem('~B~&W', nil))) )); Insert( ColorOptions ); Bounds.Assign( 24, 1, 40, 2); Insert( New( PLabel, Init( Bounds, 'Color schemes', ColorOptions ))); constructor Load(var S: TStream); Creates a new TCluster object and loads the appropriate values (TView.Load and Value and Sel fields) from stream S. function Mark(Item: Integer): Boolean; virtual; Mark is always overridden by the object that is derived from TCluster and is used to obtain the setting of the Item'th control in the cluster. If the Item'th control is set, as for example, a check box is currently selected, then Mark should return True. If the control is not currently set, then Mark should return False. See: TCheckBoxes.Mark, TRadioButtons.Mark procedure MovedTo(Item: Integer); virtual; MovedTo moves the active location within the cluster to the Item'th control. procedure Press(Item: Integer); virtual; Press is always overridden by TCluster descendants to set or clear a check box item, or to set or clear a specific radio button. procedure SetData(var Rec); virtual; SetData copies Value field from Rec and draw's the cluster. SetData is used in conjunction with GetData to access the dialog data. See Chapter 12, "Turbo Vision List Boxes" in the Borland Pascal Developer's Guide for an example. procedure SetState(AState: Word; Enable: Boolean); virtual; TCluster.SetState passes its parameters to TView.SetState, and if the view's State is sfSelected , then calls TView.DrawView. procedure Store(var S: TStream); Call's TView.Store(S) and then writes the contents of Value and Sel out to stream S. See: TCluster.Load, Chapter 15, "Streams" in the Borland Pascal Developer's Guide. TCollection object ------------------------------------------------------------ Turbo Vision Hierarchy TObject TCollection TSortedCollection TStringCollection TResourceCollection Discussion Collections provide a mechanism for storing and accessing arbitrary collections of data. You can think of a collection as working like a dynamically sizeable array of data, that can be enlarged as your data requirements increase. Several specialized collections are derived from TCollection, including TSortedCollection, TStringCollection and TResourceCollection. The latter is used internally to the resource file mechanism and is not generally used by application programs. While collections are defined within Turbo Vision, you can also use collections in standard, non-Turbo Vision applications. In the description of the methods below, each method using an Index parameter checks to insure that the Index is in the valid range between 0 and Count (the number of items in the collection). If the Index is out range, these methods call TCollection.Error which, by default, halts the program with a run time error. You can trap any collection error by overriding Error in your derived collection. See: Chapter 14, "Collections" in the Borland Pascal Developer's Guide for complete details and a tutorial on the use of the TCollections object type. Commonly Used Features TCollection.Count field, TCollection.Init, TCollection.Init, the access methods At, AtPut, AtDelete, AtFree, the iterators FirstThat, ForEach and LastThat, the IndexOf function, and the Load and Store methods. Example See Chapter 14, "Collections" in the Borland Pascal Developer's Guide, for several examples. Fields Count: Integer; Holds the number of items currently stored in the collection. Delta: Integer; Because one of the features of collections is that they can grow, Delta holds the number of elements by which the collection should be enlarged when the Count reaches the current maximum size specified by Limit. When this occurs, Limit is increased by Delta and additional space is allocated for the necessary Item pointers. Generally, Limit should initially be set to a sufficient size for most operations on the collection, and Delta should be set large enough so that expansion of the collection occurs infrequently to avoid the fairly intensive overhead of dynamically resizing the collection. See: TCollection.Init, TCollection.Limit, TCollection.Items Items: PItemList; Items points to an array that contains pointers to the individual items in the collection. Limit: Integer; Holds the current number of elements allocated to the collection. See: Delta, TCollection.Init Methods function At(Index : Integer): Pointer; Use At to access the collection as if it were an array. At(Index) returns a pointer to the Index'th item in the array, where Index ranges from 0 up to Count. See: TCollection.IndexOf() as the inverse of At procedure AtDelete(Index: Integer); AtDelete deletes the item at the location specified by Index, and slides all of the following items in the collection over to fill in the now vacant hole and decrements Count by 1. AtDelete does not dispose of the actual item that was in the location. Therefore, be sure to save a pointer to the item first, and then to separately dispose of the specific item using Dispose( ItemPtr, Done ). See: TCollection.AtFree , TCollection.Delete, TCollection.Free procedure AtFree(Index: Integer);] AtFree works like AtDelete, except that the specific item being deleted is also disposed of. If you do not need to retain a pointer to the specific item in the collection for future processing, you will probably want to use AtFree in place of AtDelete for deleting items from the collection. See:TCollection.AtDelete, TCollection.Delete, TCollection.Free procedure AtInsert(Index: Integer; Item: Pointer); AtInsert puts a new Item into the collection at the Index location by sliding all of the following items over by one position. If adding the new element would exceed the size of the collection, TCollection.SetLimit is called to automatically expand the size. See: TCollection.At,TCollection.AtPut, TCollection.SetLimit procedure AtPut(Index: Integer; Item: Pointer); Use AtPut when you need to replace an existing item with a new item. APut copies the new Item pointer to the location specified by Index. procedure Delete(Item: Pointer); The items in a collection can be accessed via their index location or by way of the pointer to the item. When you have a pointer to an item and wish to delete it, you can call Delete(Item) directly. Alternatively, you can use the IndexOf() function to translate the pointer into an Index value and then use AtDelete, like this, AtDelete(IndexOf(Item)); After an item is deleted, Count is decremented by 1. See: TCollection.AtDelete, TCollection.AtFree, TCollection.Free, TCollection.IndexOf procedure DeleteAll; Sets Count to 0, effectively deleting all items in the collection. See: TCollection.AtDelete,TCollection. Delete destructor Done; virtual; Always call a collection's Done method to dispose of each item and free up the memory used by the collection. procedure Error(Code, Info: Integer); virtual; Override: As needed. All collection errors result in a call to Error, with error information passed in Code and Info. See: coXXXX constants. function FirstThat(Test: Pointer): Pointer; FirstThat is one of the iterator functions and is normally used to search through the collection for a specific item. Test should point to a locally defined far procedure, returning True when it matches the search pattern and False otherwise. For each item in the collection until finding a match, FirstThat calls the Test function. See: Chapter 14, "Collections" for a detailed example. procedure ForEach(Action: Pointer); ForEach is an iterator function to scan through every item in the collection, and call the procedure specified by the Action pointer, passing to it a pointer to each individual item. See: Chapter 14, "Collections" for a detailed example. procedure Free(Item: Pointer); This procedure is similar to Delete, except that Free also disposes of the memory occupied by the item. Free is equivalent to calling, Delete(Item); FreeItem(Item); Although, Borland recommends not calling FreeItem directly. See: TCollection.AtFree,TCollection. AtDelete, TCollection.Delete, TCollection.FreeAll procedure FreeAll; Disposes of each item in the collection and sets Count to 0. procedure FreeItem(Item: Pointer); virtual; When Item is a pointer to an individual item in the collection, FreeItem(Item) disposes Item by calling Dispose(PObject(Item), Done), using PObject to recast the pointer to a generic PObject. See: TCollection.AtFree, TCollection.AtDelete, TCollection.Delete, Free function GetItem(var S: TStream): Pointer; virtual; GetItem is used to read a single collection item from stream S and is automatically called by TCollection.Load. You should not directly call this routine but should use Load instead. See: TCollection.Load, TCollection.PutItem, TCollection.Store function IndexOf(Item: Pointer): Integer; virtual; Given a pointer to an Item, IndexOf returns the index position in the collection where the Item is located. IndexOf is the opposite of At(Index) which returns a pointer to the item. See: TCollection.At constructor Init(ALimit, ADelta: Integer); TCollection.Init creates a new collection with space initially allocated for the number of elements specified by ALimit, and the ability to dynamically increase the size of the collection in ADelta increments. See: MaxCollectionSize procedure Insert(Item: Pointer); virtual; Inserts or adds the specified Item to the end of the collection and is equivalent to calling AtInsert(Item, Count). See: TCollection.AtInsert function LastThat(Test: Pointer); Pointer; LastThat searches backwards through the collection, beginning at the last item and moving forwards. For each item, LastThat calls the function specified by Test, until Test returns a True result. By having Test point to a function that makes a comparision between a search criteria and an item in the collection, you can use LastThat to quickly scan backwards in a collection. See: TCollection.FirstThat, TCollection.ForEach constructor Load(var S: TStream); Loads the entire collection from stream S, by calling TCollection.GetItem for each individual item in the collection. See: TCollection.GetItem procedure Pack; Use Pack to eliminate all nil pointers that may have been stored into the collection. procedure PutItem(var S: TStream; Item: Pointer); virtual; Called by TCollection.Store to write an individual item to stream S. procedure SetLimit(ALimit: Integer); virtual; Use SetLimit to manually adjust the number of elements allocated to the collection. SetLimit operates by allocating a new Items array and copying the appropriate number of elements from the old Items array into the new array. See: TCollection.Items, TCollection.Limit procedure Store(var S: TStream); Writes the entire collection to stream S. See: TCollection.Load, TCollection.PutItem TCommandSet type ------------------------------------------------------------ Declaration: TCommandSet = set of Byte; Unit: Views Purpose: In Turbo Vision, command codes are assigned values from 0 to 65,535, with values in the range of 0 to 255 reserved for items that can be selectively disabled. TCommandSet is used to hold a set of up to 256 commands, specifically those that can be disabled, and is used as a parameter for the TView methods, EnableCommands, DisableCommands, GetCommands and SetCommands. Listing TCMDSET.PAS illustrates the use of a TCommandSet type. 1 { TCMDSET.PAS } 2 { Example using TCommandSet, from TVSHELL8.PAS } 3 var 4 CommandsOn : TCommandSet; 5 CommandsOff : TCommandSet; 6 ... 7 CommandsOn := [cmUseDOS, cmDelete]; 8 CommandsOff := CommandsOn; 9 10 if (SetUpData.ProgOptions and 2) = 2 then 11 CommandsOff := CommandsOff - [cmUseDOS]; 12 13 if (SetUpData.ProgOptions and 4) = 4 then 14 CommandsOff := CommandsOff - [cmDelete]; 15 16 CommandsOn := CommandsOn - CommandsOff; 17 18 DisableCommands( CommandsOff ); 19 EnableCommands( CommandsOn ); TDeskTop object ------------------------------------------------------------ Turbo Vision Hierarchy TObject TView TGroup TDeskTop TWindow TProgram Discussion Each application has one TDeskTop object, pointed to by the global variable, DeskTop, that controls the area on the screen between the menu bar and the statusline. The TDeskTop object owns the TBackground that forms the backdrop for the screen, and typically owns other windows and dialogs that become inserted into the desktop during program execution. Commonly Used Features TDeskTop provides two functions for rearranging the windows: Cascade and Tile. Most applications will not need to manipulate the TDeskTop object other than to insert windows and control the operation of dialogs through the inherited ExecView method. If you wish to change the background object, you'll need to derive a new TDeskTop object and override the InitBackground procedure described below. Example Windows used by the application are normally inserted into the TDeskTop object. For example, the TVSHELL sample program (see Chapters 11-12 of the Borland Pascal Developer's Guide) creates and inserts a directory window using the global DeskTop^ pointer, like this: GetExtent( Bounds ); Bounds.B.Y := Bounds.B.Y - 2; { We leave space for the status line } DirWindow := New( PDirectoryWindow, Init(Bounds, 'Directory Listing', 0 )); DeskTop^.Insert(DirWindow); Modal dialog boxes are displayed on the desktop by calling the ExecView method, like this: { Let the user fiddle with the dialog box } Control := DeskTop^.ExecView (Dialog); if Control <> cmCancel then begin Dialog^.GetData( SetUpData ); ... end; Non-modal dialog boxes are treated the same as a window and are inserted directly using Insert, as shown in the directory window example above. For an example of deriving a TDeskTop object to implement a new background, see TBackground. Fields Background: PBackground; Points to the TBackground object owned by this TDeskTop (note: This field is omitted from the Borland documentation). Methods procedure Cascade(var R: TRect); Calling Cascade produces a "cascade effect" of all the windows currently owned by the desktop. The effect is identical to that used by the IDE editor when multiple files are opened: the window that appears farthest to the back is drawn to occupy the entire screen, and then each subsequent window is sized and positioned such that its upper left corner appears one line down and one character to the right of the window behind it. See: TDeskTop.Tile constructor Init(var Bounds : TRect ); Init creates a new TDeskTop with the size and position given by Bounds, and then calls InitBackground to create a new TBackground object. See: TBackground, TDeskTop.InitBackground procedure InitBackground; virtual; Override: As needed to create new TBackground objects InitBackground calls TBackground.Init to instantiate a new background object, and sets Background to point to the TBackground object. If you wish to create a different appearing background thann the default background, there are two ways to go about it. One is to merely insert a new TBackground object into the desktop so that it hides the previous desktop. To do this, you would write, DeskTop^.Insert(New(PBackground, Init(Bounds, #FF)); where Bounds defines the size and location of the new background object, and #FF is a hexadecimal character describing the pattern to use in drawing the new backdrop. While this method is easy to implement, the original background continues to occupy memory. A better approach is to use the method given as an example in the TBackground section, where a new TDeskTop object is derived and its InitBackground function is overridden to instantiate a new TBackground. Using this approach, when the application runs, it automatically calls your TDesktop-derived object's InitBackground method, creating only one new background. See: TBackground for complete details. Important: Borland's documentation describes a method called NewBackground to perform the operation of InitBackground. However, in the actual implementation of Turbo Vision, NewBackground was replaced with InitBackground. procedure HandleEvent(var Event: TEvent); virtual; TDeskTop.HandleEvent exists primarily to intercept the F6 key, used to cycle through the collection of windows that it owns. function NewBackground: PView; virtual; This function, described in the Borland documentation does not exist. See InitBackground. procedure Tile(var R: TRect); Displays tileable windows, in tiled format, on to the screen. procedure TileError; virtual; Override: As needed. If for some reason Turbo Vision is unable to rearrange and draw the windows in either cascaded or tiled format, Turbo Vision will call the TDeskTop.TileError procedure. Normally, this procedure does nothing and returns. However, if you wish to detect the condition and provide a message to the user, you can override this procedure. TDialog object ------------------------------------------------------------ Turbo Vision Hierarchy TObject TView TGroup TWindow TDialog Discussion Use TDialog to derive new types of dialog box objects. In most cases, you will use the existing TDialog-type directly, and only reference its Init method. Dialogs are then inserted into the desktop, or executed via DeskTop^.ExecView. Generally, you will not need to access the dialog methods directly. By default, dialog boxes cannot grow, but can be dragged or closed via a close icon. Fields None Methods function GetPalette: PPalette; virtual; Override: As needed to define new color mappings. Returns a pointer to the CDialog palette, defining the basic color mappings for dialogs and all the controls that are inserted into dialogs. procedure HandleEvent(var Event: TEvent); virtual; Adds special processing of events to generate cmCancel, cmDefault, cmYes or cmNo commands in response to the appropriate inputs. constructor Init(var Bounds: TRect; ATitle: TTitleStr); Passes the parameters Bounds and ATtitle to TWindow.Init to create a dialog box window with defaults set such that the dialog window cannot grow but can be dragged or closed. function Valid(Command: Word): Boolean; virtual; If the Command parameter equals cmCommand, then Valid returns True. Otherwise, when Command is cmValid (or zero), Valid checks the Valid method of each of the controls that it owns in order to determine if the entire dialog was constructed satisfactorily. All of the controls must return True in order for TDialog.True to return True. See: TView.Valid, Chapters 16 and 19. TDosStream object ------------------------------------------------------------ Turbo Vision Hierarchy TObject TStream TDosStream TBufStream Discussion Use TDosStream for unbuffered stream file access (see also TBufStream). For most applications you will probably prefer to use TBufStream for its faster, buffered file access. See TStream, TBufStream, stXXXX constants Commonly Used Features Generally, you will use the TDosStream.Init method to open a stream file for access, the TDosStream.Read and TDosStream.Write methods for performing input and output, and TDosStream.Done to close and dispose of the object. For random access streams, you will use TBufStream.Seek to position the file pointer to the proper object record. Example The use of TDosStream is nearly identical to TBufStream, without the buffering related methods. See the TBufStream example and also Chapter 15, "Streams" in the Borland Pascal Developer's Guide for information regarding the use of streams. Fields Handle: Word; { Read only } Contains the DOS file handle used to access the file containing the stream. Methods destructor Done; virtual; Closes the file and disposes of the stream object. function GetPos: Longnt; virtual; Override: Never. Gives the stream's current position, in bytes, relative to the start of the stream. function GetSize: Longint; virtual; Override: Never. Returns the total number of bytes in the stream. constructor Init( Filename: FNameStr; Mode, Size : Word); Use Init to create and initialize a stream, using the parameters Filename for the name of the file to open, and setting the Mode parameter to stCreate, stOpenRead, stOpenWrite or stOpen. procedure Read( var Buf; Count: Word); virtual; Override: Never Use Read to read Count bytes from the stream and into the Buf parameter. Read begins at the stream's current position (as determined by Seek or beginning at the end of the previous Read operation). See: Chapter 15, "Streams", TOosStream.Seek, TDosStream.Write procedure Seek(Pos : Longint); virtual; Override: Never. Positions the current stream position to Pos. You can use Seek to implement random access to stream files (see Chapter 15, "Streams"). Be certain that if you are adding or multiplying values to compute the Pos parameter (for example, SizeOf(SomeObject) * Index), that you convert the parameters to Longint to avoid integer overflow errors. See: Chapter 15, "Streams", TDosStream.GetPos,TDosStream.Read, TDosStream.Write procedure Truncate; virtual; Override: Never. Use Truncate to delete all data following the current position in the stream. procedure Write( var Buf; Count: Word); virtual; Override: Never. Use Write to copy Count bytes from the Buf parameter to the stream. See: Chapter 15, "Streams", TDosStream.Read TDrawBuffer type ------------------------------------------------------------ Declaration: TDrawBuffer = arrayu[0..MaxViewWidth-1] of Word; Unit: Views Purpose: TDrawBuffer is used to create temporary storage areas for a line of text to be written to the screen where the low byte of each word contains the character value, and the high byte contains the video attribute byte. You can use the Turbo Vision procedures, MoveBuf, MoveChar, MoveCStr, and MoveStr to set up the buffer and then use one of the TView method's WriteBuf or WriteLine within a Draw method to write the output to the screen. Here's an example using TDrawBuffer: var Buffer : TDrawBuffer; ... MoveStr(Buffer, 'Financial Results for FY1991', GetColor(1) ); WriteLine( 1, 3, 28, 1, Buffer ); See: TView methods WriteBuf and WriteLine. TEmsStream object ------------------------------------------------------------ Turbo Vision Hierarchy TObject TStream TEmsStream Discussion Use TEmsStream for storing stream files in EMS memory. Important: If you fail to call TEmsStream.Done, or if your program suffers an abnormal termination (i.e. "crashes"), the EMS will remain allocated. The only way to recover allocated EMS is to reboot the computer. See: TStream, TBufStream, TDosStream, stXXXX constants Commonly Used Features Generally, you will use the TEmsStream.Init method to open a stream for access, the TEmsStream.Read and TEmsStream.Write methods for performing input and output, and TEmStream.Done to close and dispose of the object. For random access streams, you will use TEmsStream.Seek to position the file pointer to the proper object reocrd. Example See Chapter 15, "Streams" for a tutorial and examples of using TEmsStream. Fields Handle: Word; { Read only } Contains the EMS file handle used to access the stream. PageCount: Word; Contains the total number of 16k byte pages allocated for the TEmsStream object. Position: Longint; Contains the current location within the stream, beginning from byte 0. Size: Longint; Contains the total size of the stream, in bytes. Methods destructor Done; virtual; Disposes and releases the EMS memory pages used by the stream. function GetPos: Longnt; virtual; Override: Never. Gives the stream's current position, in bytes, relative to the start of the stream. function GetSize: Longint; virtual; Override: Never. Returns the total number of bytes in the stream. constructor Init( MinSize, MaxSize : Longint); Use Init to create an initialize the TEmsStream such that the stream will always have at least the minimum specified MinSize memory allocated to it. The exact allocation depends on the version of the EMS driver in use on your computer. If your EMS driver is version 4.0 or greater, then MaxSize is ignored. In 4.0 and greater, EMS blocks are dynamically resizeable so this parameter is ignored. Prior to version 4.0, the EMS blocks could not be resized and in that case Init will initially try to allocate the entire MaxSize bytes. procedure Read( var Buf; Count: Word); virtual; Override: Never Use Read to read Count bytes from the stream and into the Buf parameter. Read begins at the stream's current position (as determined by Seek or beginning at the end of the previous Read operation). See: Chapter 15, "Streams" in the Borland Pascal Developer's Guide, TEmsStream.Seek, TEmsStream.Write procedure Seek(Pos : Longint); virtual; Override: Never. Positions the current stream position to Pos. You can use Seek to implement random access to streams (see Chapter 15, "Streams"). Be certain that if you are adding or multiplying values to compute the Pos parameter (for example, SizeOf(SomeObject) * Index), that you convert the parameters to Longint to avoid integer overflow errors. See: Chapter 15, "Streams", TEmsStream.GetPos,TEmsStream.Read, TEmsStream.Write procedure Truncate; virtual; Override: Never. Use Truncate to delete all data following the current position in the stream, resetting the current position to the end of the stream. procedure Write( var Buf; Count: Word); virtual; Override: Never. Use Write to copy Count bytes from the Buf parameter to the stream. See: Chapter 15, "Streams", TEmsStream.Read TEvent type ------------------------------------------------------------ Declaration: The TEvent type, as defined in Turbo Pascal 6.0, (C) Copyright 1991, by Borland Intl: 1 { TEVENT.PAS } 2 PEvent = ^TEvent; 3 TEvent = record 4 What: Word; 5 case Word of 6 evNothing: (); 7 evMouse: ( 8 Buttons: Byte; 9 Double: Boolean; 10 Where: TPoint); 11 evKeyDown: ( 12 case Integer of 13 0: (KeyCode: Word); 14 1: (CharCode: Char; 15 ScanCode: Byte)); 16 evMessage: ( 17 Command: Word; 18 case Word of 19 0: (InfoPtr: Pointer); 20 1: (InfoLong: Longint); 21 2: (InfoWord: Word); 22 3: (InfoInt: Integer); 23 4: (InfoByte: Byte); 24 5: (InfoChar: Char)); 25 end; Unit: Drivers Purpose: TEvent is a case variant record defining each type of event used in Turbo Vision. When a routine receives an event, it can look in the TEvent fields to determine what type of event occurred and use other information provided to appropriately process that event. For example, when the TEvent.What field contains evMouse, you can check TEvent.Buttonsto see which mouse button was pressed (0=none, 1=left, 2=right). The TEvent.Double flag is set if two mouse clicks occurred within the DoubleDelay time interval. Lastly, for each mouse event, TEvent.Where contains the coordinates of the mouse. When the event record contains broadcast evMessage events, several variant fields are provided for passing additional information with the message. InfoPtr can be used, for instance, to pass a pointer to a record or another object. See: Chapter 13, "More Turbo Vision Features" in the Borland Pascal Developer's Guide for additional information regarding event processing, and also see the HandleEvent method defined in various object types.